home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / util4 / akcc36.lha / Programmers / Docs / Reference_ENG.doc < prev    next >
Text File  |  1995-08-08  |  13KB  |  662 lines
  1.  
  2.    $VER: Reference_ENG.doc V37.3 (25.7.94)
  3.  
  4.    © 1989-94 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.        Andreas R. Kleinert,
  9.        Grube Hohe Grethe 23,
  10.        D-57074 Siegen,
  11.        Germany.                        email : Fido 2:2457/345.10
  12.                                                (checked weekly)
  13.  
  14.  
  15.    Here is a listing of all currently available functions of the
  16.    akcc_gen0.library in an Autodoc-like style of description :
  17.  
  18.         AKCC_StoreFile             ; since Version V35
  19.         AKCC_GetDate
  20.         AKCC_WildCmp
  21.         AKCC_Paths
  22.         AKCC_CopyFile
  23.         AKCC_TestEntry
  24.         AKCC_BStrCpy
  25.         AKCC_GetName
  26.         AKCC_FPrintf
  27.         AKCC_DelEnv
  28.         AKCC_ReadEnv
  29.         AKCC_WriteEnv
  30.         AKCC_Assign
  31.         AKCC_UnLineStr             ; since Version V36
  32.         AKCC_AddPathLock
  33.         AKCC_AddPathName
  34.         AKCC_RemPathName
  35.         AKCC_ParseText
  36.         AKCC_CheckAvailDevice      ; since Version V37
  37.         AKCC_SetDate
  38.  
  39.  
  40. -----------------------------------------------------------------------------
  41.    Functions available since Version 35 :
  42. -----------------------------------------------------------------------------
  43.  
  44.    NAME
  45.         AKCC_StoreFile
  46.  
  47.    SYNOPSIS
  48.  
  49.         BYTE *AKCC_StoreFile(UBYTE *name, ULONG *bytes)
  50.                              A1           A2
  51.  
  52.    FUNCTION
  53.  
  54.         Loads a file into a buffer.
  55.  
  56.         Returns a pointer to the buffer or NULL.
  57.         BufferSize is stored in "bytes".
  58.  
  59.    INPUT(S)
  60.  
  61.         name  - FilePath
  62.         bytes - Pointer to ULONG
  63.  
  64.    RESULT
  65.  
  66.         Buffer, which contains the whole File or NULL.
  67.         Has to be freed via FreeMem() after use if non-NULL.
  68.  
  69.    SEE ALSO
  70.  
  71.         AKCC_CopyFile
  72.  
  73. -----------------------------------------------------------------------------
  74.  
  75.    NAME
  76.         AKCC_GetDate
  77.  
  78.    SYNOPSIS
  79.  
  80.         struct DateStruct *AKCC_GetDate(struct DateStamp *dos_rawdate)
  81.                                         A1
  82.    FUNCTION
  83.  
  84.         Converts a DOS DateStamp structure into a more common,
  85.         human readable, format.
  86.  
  87.         Returns a pointer to a structure or NULL.
  88.  
  89.    INPUT(S)
  90.  
  91.         dos_rawdate - Pointer to DateStamp-Struktur
  92.  
  93.    RESULT
  94.  
  95.         Pointer to DateStruct or NULL.
  96.         Has to be freed via FreeMem() after use if non-NULL.
  97.  
  98.    SEE ALSO
  99.  
  100.         DOS' date-functions
  101.  
  102. -----------------------------------------------------------------------------
  103.  
  104.    NAME
  105.         AKCC_WildCmp
  106.  
  107.    SYNOPSIS
  108.         long AKCC_WildCmp(UBYTE *orig, UBYTE *wild)
  109.                           A1           A2
  110.    FUNCTION
  111.  
  112.         Performs a WildCard comparion between a wildcard-string (wild)
  113.         and a usual string, which does not contain any wildcards (orig).
  114.  
  115.    INPUT(S)
  116.  
  117.         orig - non-wildcard string to compare
  118.         wird - wildcard-string for comparison
  119.  
  120.    RESULT
  121.  
  122.         TRUE  for "wildcard matches",
  123.         FALSE for "wildcard does not match" (or error).
  124.  
  125.    SEE ALSO
  126.  
  127.         -
  128.  
  129. -----------------------------------------------------------------------------
  130.  
  131.    NAME
  132.         AKCC_Paths
  133.  
  134.    SYNOPSIS
  135.  
  136.         long AKCC_Paths(UBYTE *name, UBYTE *rootdir, UBYTE *dir, UBYTE *comp)
  137.                         A1           A2              A3          A4
  138.  
  139.    FUNCTION
  140.  
  141.         Splits a Dir(File)Path into two (three) parts :
  142.  
  143.          - rootdir : RootDirPath (without "/", but with ":", if Device)
  144.          - dir     : DirPath     (with "/", if no Device)
  145.          - comp    : FileName    (may contain WildCards)
  146.  
  147.    INPUT(S)
  148.  
  149.         name    - path to split
  150.         rootdir - Pointer to buffer for RootDirPath
  151.         dir     - Pointer to buffer for DirPath
  152.         comp    - Pointer to buffer for FileName
  153.  
  154.    RESULT
  155.  
  156.         TRUE for "was a DirPath",
  157.         FALSE for "was a FilePath".
  158.  
  159.         Do not use this value for any plausibility checks on Files/Dirs.
  160.         It may be wrong for your purposes.
  161.  
  162.    SEE ALSO
  163.  
  164.         -
  165.  
  166. -----------------------------------------------------------------------------
  167.  
  168.    NAME
  169.         AKCC_CopyFile
  170.  
  171.    SYNOPSIS
  172.  
  173.         long AKCC_CopyFile(UBYTE *sourcename, UBYTE *destname)
  174.                            A1                 A2
  175.  
  176.    FUNCTION
  177.  
  178.         Copies a file (sourcename) to an other (destname).
  179.         Buffer allocation and delocation is done auto- and dynamically.
  180.  
  181.    INPUT(S)
  182.  
  183.         sourcename - Name of SourceFile
  184.         destname   - Name of DestFile
  185.  
  186.    RESULT
  187.  
  188.         TRUE for "action succesful",
  189.         FALSE for "error occured".
  190.  
  191.    SEE ALSO
  192.  
  193.         AKCC_StoreFile
  194.  
  195. -----------------------------------------------------------------------------
  196.  
  197.    NAME
  198.         AKCC_TestEntry
  199.  
  200.    SYNOPSIS
  201.  
  202.         long AKCC_TestEntry(UBYTE *entryname)
  203.                             A1
  204.  
  205.    FUNCTION
  206.  
  207.         Make some "trial-and-error" assumptions about the given
  208.         "entryname" to find out, whether it's a File, Dir or
  209.         virtual (!) Device (e.g. "CON").
  210.  
  211.         Does some Open() and Lock() calls to decide this logically.
  212.  
  213.    INPUT(S)
  214.  
  215.         entryname - Name of the "objektes"
  216.  
  217.    RESULT
  218.  
  219.         Special code, descrbing the "object" (see Includes)
  220.  
  221.    SEE ALSO
  222.  
  223.         -
  224.  
  225. -----------------------------------------------------------------------------
  226.  
  227.    NAME
  228.         AKCC_BStrCpy
  229.  
  230.    SYNOPSIS
  231.  
  232.         void AKCC_BStrCpy(UBYTE *dest, UBYTE *bstr, UBYTE *hangon)
  233.                           A1           A2           A3
  234.  
  235.    FUNCTION
  236.  
  237.         Copies a BCPL-String to a C-String and concatenates "hangon"
  238.         to it (if non-NULL).
  239.  
  240.         This is e.g. useful to create a Device-Name from a
  241.         BSTR ( BSTR: "DF0" -> C-STR: "DF0:").
  242.  
  243.    INPUT(S)
  244.  
  245.         dest   - Pointer to string buffer
  246.         bstr   - Pointer to BCPL-String
  247.         hangon - Pointer to string or NULL.
  248.  
  249.    RESULT
  250.  
  251.         -
  252.  
  253.    SEE ALSO
  254.  
  255.         -
  256.  
  257. -----------------------------------------------------------------------------
  258.  
  259.    NAME
  260.         AKCC_GetName
  261.  
  262.    SYNOPSIS
  263.  
  264.         void AKCC_GetName(BPTR dest, BPTR fl, UBYTE *name)
  265.                           A1         A2       A3
  266.  
  267.    FUNCTION
  268.  
  269.         Get full Path of a File/Dir from a Lock (BPTR).
  270.  
  271.         The _same_ lock has to be passed twice (one copy is used as
  272.         a break condition for this recursive called function).
  273.  
  274.    INPUT(S)
  275.  
  276.         dest   - File/Dir Lock (BPTR)
  277.         fl     - same as dest
  278.         name   - string buffer for the resulting path
  279.                  (at least 256 Bytes)
  280.  
  281.    RESULT
  282.  
  283.         -
  284.  
  285.    SEE ALSO
  286.  
  287.         -
  288.  
  289. -----------------------------------------------------------------------------
  290.  
  291.    NAME
  292.         AKCC_FPrintf
  293.  
  294.    SYNOPSIS
  295.  
  296.         void AKCC_FPrintf(BPTR outhandle, UBYTE *text, APTR pararr)
  297.                           A1              A2           A3
  298.  
  299.    FUNCTION
  300.  
  301.         Similar to "printf()", but uses RawDoFmt() to perform the output.
  302.  
  303.         Parameters have to be passed in an ULONG array (remember to
  304.         specify "%lc" instead of "%c", etc.).
  305.         The resulting string is written to outhandle (e.g. Output()).
  306.  
  307.    INPUT(S)
  308.  
  309.         outhandle - DosHandle for write-accesses
  310.         text      - format string (printf)
  311.         pararr    - array of args for format string
  312.  
  313.    RESULT
  314.  
  315.         -
  316.  
  317.    SEE ALSO
  318.  
  319.         AKCC_ParseText
  320.  
  321. -----------------------------------------------------------------------------
  322.  
  323.    NAME
  324.         AKCC_DelEnv
  325.  
  326.    SYNOPSIS
  327.  
  328.         long AKCC_DelEnv(UBYTE *var)
  329.                          A1
  330.  
  331.    FUNCTION
  332.  
  333.         Deletes an ENV-Variable.
  334.  
  335.    INPUT(S)
  336.  
  337.         var     - variable name
  338.  
  339.    RESULT
  340.  
  341.         Boolean.
  342.  
  343.    SEE ALSO
  344.  
  345.         AKCC_ReadEnv, AKCC_WriteEnv
  346.  
  347. -----------------------------------------------------------------------------
  348.  
  349.    NAME
  350.         AKCC_ReadEnv
  351.  
  352.    SYNOPSIS
  353.  
  354.         long AKCC_ReadEnv(UBYTE *var, UBYTE *content)
  355.                           A1          A2
  356.  
  357.    FUNCTION
  358.  
  359.         Reads an ENV-Variable to a buffer.
  360.  
  361.    INPUT(S)
  362.  
  363.         var     - variable name
  364.         content - buffer for content of variable
  365.  
  366.    RESULT
  367.  
  368.         Boolean.
  369.  
  370.    SEE ALSO
  371.  
  372.         AKCC_DelEnv, AKCC_WriteEnv
  373.  
  374. -----------------------------------------------------------------------------
  375.  
  376.    NAME
  377.         AKCC_WriteEnv
  378.  
  379.    SYNOPSIS
  380.  
  381.         long AKCC_WriteEnv(UBYTE *var, UBYTE *content)
  382.                            A1          A2
  383.  
  384.    FUNCTION
  385.  
  386.         Writes/Creates an ENV-Variable from a buffer.
  387.  
  388.    INPUT(S)
  389.  
  390.         var     - variable name
  391.         content - content of variableü
  392.    RESULT
  393.  
  394.         Boolean.
  395.  
  396.    SEE ALSO
  397.  
  398.         AKCC_DelEnv, AKCC_ReadEnv
  399.  
  400. -----------------------------------------------------------------------------
  401.  
  402.    NAME
  403.  
  404.         AKCC_Assign
  405.  
  406.    SYNOPSIS
  407.  
  408.         long AKCC_Assign(UBYTE *ass_name, UBYTE *ass_path)
  409.                          A1               A2
  410.  
  411.    FUNCTION
  412.  
  413.         Assigns "ass_name" (e.g. "SYS:") to ass_path (e.g. "DF0:"
  414.         or "DF0:Sys".
  415.  
  416.         Assigns to Files are legal and possible.
  417.  
  418.    INPUT(S)
  419.  
  420.         ass_name - AssignName (ended with ":")
  421.         ass_path - AssignPath
  422.  
  423.    RESULT
  424.  
  425.         Boolean.
  426.  
  427.    SEE ALSO
  428.  
  429.         -
  430.  
  431. -----------------------------------------------------------------------------
  432.    Functions available since Version 36 :
  433. -----------------------------------------------------------------------------
  434.  
  435.    NAME
  436.  
  437.         AKCC_UnLineStr
  438.  
  439.    SYNOPSIS
  440.  
  441.         void AKCC_UnLineStr(UBYTE *dest, UBYTE *source)
  442.                             A1           A2
  443.  
  444.    FUNCTION
  445.  
  446.         Removes any controlcodes (return, linefeed, etc)
  447.         from a string to minimize side-effects, when displaying it.
  448.  
  449.    INPUT(S)
  450.  
  451.         dest   - destination buffer
  452.         source - source string
  453.  
  454.    RESULT
  455.  
  456.         -
  457.  
  458.    SEE ALSO
  459.  
  460.         -
  461.  
  462. -----------------------------------------------------------------------------
  463.  
  464.    NAME
  465.  
  466.         AKCC_AddPathLock
  467.  
  468.    SYNOPSIS
  469.  
  470.         long AKCC_AddPathLock(BPTR lock)
  471.                               A1
  472.  
  473.    FUNCTION
  474.  
  475.         Adds a new Path to the search-list of the CLI/Shell.
  476.  
  477.         Uses a Lock as source.
  478.  
  479.    INPUT(S)
  480.  
  481.         lock - lock to a directory
  482.  
  483.    RESULT
  484.  
  485.         Boolean.
  486.  
  487.    WARNING
  488.  
  489.         Be careful using this function under OS V36.
  490.         Read the Includes for more information.
  491.  
  492.    SEE ALSO
  493.  
  494.         AKCC_AddPathName, AKCC_RemPathName, AKCC_GetName
  495.  
  496. -----------------------------------------------------------------------------
  497.  
  498.    NAME
  499.  
  500.         AKCC_AddPathName
  501.  
  502.    SYNOPSIS
  503.  
  504.         long AKCC_AddPathName(UBYTE *name)
  505.                               A1
  506.  
  507.    FUNCTION
  508.  
  509.         Adds a new Path to the search-list of the CLI/Shell.
  510.  
  511.         Uses a PathName as source.
  512.  
  513.    INPUT(S)
  514.  
  515.         name - PathName
  516.  
  517.    RESULT
  518.  
  519.         Boolean.
  520.  
  521.    WARNING
  522.  
  523.         Be careful using this function under OS V36.
  524.         Read the Includes for more information.
  525.  
  526.    SEE ALSO
  527.  
  528.         AKCC_AddPathLock, AKCC_RemPathName
  529.  
  530. -----------------------------------------------------------------------------
  531.  
  532.    NAME
  533.  
  534.         AKCC_RemPathName
  535.  
  536.    SYNOPSIS
  537.  
  538.         long AKCC_RemPathName(UBYTE *name)
  539.                               A1
  540.  
  541.    FUNCTION
  542.  
  543.         Removes a Path from the search-list of the CLI/Shell.
  544.  
  545.         Uses a PathName as source.
  546.  
  547.    INPUT(S)
  548.  
  549.         name - PathName
  550.  
  551.    RESULT
  552.  
  553.         Boolean.
  554.  
  555.    WARNING
  556.  
  557.         Be careful using this function under OS V36.
  558.         Read the Includes for more information.
  559.  
  560.    SEE ALSO
  561.  
  562.         AKCC_AddPathName, AKCC_AddPathLock
  563.  
  564. -----------------------------------------------------------------------------
  565.  
  566.    NAME
  567.  
  568.         AKCC_ParseText
  569.  
  570.    SYNOPSIS
  571.  
  572.         void AKCC_ParseText(UBYTE *orig, UBYTE *new)
  573.                             A1           A2
  574.  
  575.    FUNCTION
  576.  
  577.         Parses a string, which may contain many special control-codes.
  578.  
  579.         Output may e.g. be printed by AKCC_FPrintf() or any other
  580.         output function.
  581.  
  582.    INPUT(S)
  583.  
  584.         orig - formatted text (see Includes for details)
  585.         new  - resulting output string
  586.                (controlcodes replaced by their "content")
  587.  
  588.    RESULT
  589.  
  590.         -
  591.  
  592.    SEE ALSO
  593.  
  594.         AKCC_FPrintf, C-Ausgabe-functionen, DOS-Ausgabe-functionen
  595.  
  596. -----------------------------------------------------------------------------
  597.    Functions available since Version 37 :
  598. -----------------------------------------------------------------------------
  599.  
  600.    NAME
  601.  
  602.         AKCC_CheckAvailDevice
  603.  
  604.    SYNOPSIS
  605.  
  606.         long AKCC_CheckAvailDevice(UBYTE *dev_name)
  607.                                    A1
  608.  
  609.    FUNCTION
  610.  
  611.         Checks, if a special Device (e.g. "PRT:", "NEWCON:")
  612.         is available, without trying to actually open it.
  613.  
  614.         This only works for Devices (no Volumes or Dirs).
  615.        
  616.         NO REQUESTER WILL APPEAR, if the Device is NOT AVAILABLE !
  617.         (Dos-Lists are read and checked.)
  618.  
  619.    INPUT(S)
  620.  
  621.         dev_name - DeviceName
  622.  
  623.    RESULT
  624.  
  625.         Boolean.
  626.  
  627.    SEE ALSO
  628.  
  629.         AKCC_Assign
  630.  
  631. -----------------------------------------------------------------------------
  632.  
  633.    NAME
  634.  
  635.         AKCC_SetDate
  636.  
  637.    SYNOPSIS
  638.  
  639.         long AKCC_SetDate(struct DateStruct *gd_date)
  640.                           A1
  641.  
  642.    FUNCTION
  643.  
  644.         Resets the internal CIA-Timers to reflect the Date, which
  645.         is passed in "gd_date".
  646.  
  647.         The RealTimeClock is NOT set (too may derivates).
  648.  
  649.    INPUT(S)
  650.  
  651.         gd_date - DateStruct pointer (e.g. returned by AKCC_GetDate())
  652.  
  653.    RESULT
  654.  
  655.         -
  656.  
  657.    SEE ALSO
  658.  
  659.         AKCC_GetDate
  660.  
  661. -----------------------------------------------------------------------------
  662.